Integrating Web SDK with Telegram Mini-apps

Learn how to integrate Web SDK with your Telegram Mini-app or Game for seamless web3 functionality.

This guide will walk you through setting up Web SDK with your Telegram Mini-app or Game, enabling web3 functionality on EVM chains for your users for email and guest authentication methods.

Prerequisites

Before starting, ensure you have:

• A Telegram account
• Account and Access to Cloudflare Dashboard

Integration Steps

1. Create a Telegram Bot with BotFather

   1. Open Telegram and search for “@BotFather”
   2. Start a conversation by clicking “Start” or typing /start
   3. Create a new bot by typing /newbot
   4. Follow the prompts:
      • Enter a name for your bot
      • Choose a username (must end in ‘bot’)
2. Obtain Required Tokens

   After creating your bot, BotFather will provide:

   • Bot Token (HTTP API Token)
   • Bot Username

   Save these credentials - you’ll need them for the next steps.

   Never share or commit your bot token. It should be treated as a secret.

3. Install and Configure Your Project

   1. Clone the Sequence Telegram starter:

   git clone https://github.com/0xsequence-demos/telegram-kit-embedded-wallet-react-boilerplate
   

   2. Copy the example files in your project root:

   cp .env.example .env && cp example.wrangler.toml wrangler.toml
   

   Update the .env file with the VITE_PROJECT_ACCESS_KEY and VITE_WAAS_CONFIG_KEY with your keys from Sequence Builder after configuration.

   3. Install dependencies:

   pnpm install
   

   4. Build the app:

   pnpm run build
   

   4. Update the VARS in the wrangler.toml file with a user provided secret for BOT_SECRET and the bot token from BotFather for BOT_TOKEN.
4. Authenticate with Cloudflare Account

   Deploy the app and functions logic to Cloudflare

   1. Run pnpm wrangler pages deploy

   This will prompt you to authenticate with Cloudflare if not already logged in. On successful deploy, copy the URL where your application is now hosted.

5. Register Webhook with Telegram

   Now we call our registerWebhook endpoint on our app to register the webhook function with the URL of your deployed application to enable access for the Telegram API.

   curl -X POST \
        "<YOUR_CLOUDFLARE_DEPLOYED_URL>/api/registerWebhook"
   

6. Update Allowed Origins

   Ensure in your wallet configuration you have added the URL of your deployed application as an allowed origin through the configuration page on Sequence Builder.

7. Test out the Bot!

   Send a message to your bot on Telegram and see if it responds! It should answer you with the ability to share, play and get more info on bot.

From here, you have a fully functional Telegram bot that can interact with Sequence Embedded wallets for all integrated EVM chains. You can customize the bot responses and the client side application with functionalities specific to your game or app - simply redeploy and update the allowed origins!

Going to production

For your BOT_TOKEN, you can encrypt and store it in Cloudflare via the following command to prevent data leaks:

pnpm wrangler pages secret put BOT_TOKEN

Enter in your bot token when prompted.